<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
          "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <title>CurrencyConverter HOWTO</title>
    <link rel="stylesheet" type="text/css" href="../stylesheets/styles.css" />
  </head>

  <body>

    <div class="title">
      <h1>Building the User Interface on "Tiger"</h1>
    </div>

    <div class="body-text">
      <p>If you are using Mac OS X 10.4.x ("Tiger") to build your
      application, then the Apple tutorial's section on building the
      UI may be somewhat confusing. Apple's tutorial uses
      InterfaceBuilder 3.x to show how to build an interface, and
      there were many interface changes between versions 2.x and 3.x
      of InterfaceBuilder. In this section we see how to build the UI
      using InterfaceBuilder 2.x.</p>

      <div class="section-head">
        <h2>Launch InterfaceBuilder</h2>
      </div>

      <p>Start by locating Apple's InterfaceBuilder application. If
        you installed Apple's Developer Tools, InterfaceBuilder should
        be in the folder "/Developer/Applications/":</p>

      <div class="inline-image">
        <img src="../images/finder-win2.jpg"alt="" 
             border='0'/>
      </div>
    
      <p class= "note"><strong><em>NOTE:</em></strong> If you have not
        installed Apple's Developer Tools, you should do that now. You
        will not be able to build the CurrencyConverter example
        without them. The Developer Tools are distributed as an
        optional install with Mac OS X 10.4 ("Tiger"). Look for the
        "XCode Tools" package in the "Optional Installs" folder on the
        Mac OS 10.4 install disk.</p>

      <p>Once you have located InterfaceBuilder, double-click to launch
        the application. InterfaceBuilder presents a window you can use
        to choose a template for the nibfile you are going to create.</p>

      <div class="inline-image">
        <img src="../images/ibwin-tiger1.jpg"alt="" 
             border='0'/>
      </div>

      <p>Make sure the "Application" option is selected in the "Cocoa"
      section and click the "New" button to create a new
      nibfile. InterfaceBuilder creates a new application nibfile, but
      doesn't immediately save it. The Objective-C objects that
      represent the new application's interface appear in a new
      untitled window:</p>

      <div class="inline-image">
        <img src="../images/ibwin-tiger2.jpg"alt="" 
             border='0'/>
      </div>

      <p>The intial window and menubar also appear on the screen. The
      new application's name appears in the menus as
      "NewApplication". Save the new nibfile into the
      "currency-converter" folder that you created earlier
      (on <a href="making_project.html">this page</a>). Give the new
      file the name "CurrencyConverter.nib"</p>

      <div class="note">
        <p><strong><em>NOTE:</em></strong> Most Objective-C application projects use a main
        nibfile called "MainMenu.nib", and if you use XCode to create
        a new application project, it creates a nibfile with that
        name. Apple's CurrencyConverter tutorial assumes that the
        name of the main nibfile is "MainMenu.nib".</p>

        <p>So, why do we tell you to use a different name? Clozure CL
          has a main nibfile built into it, whose name is
          "MainMenu.nib". Normally you don't see it, and don't even
          need to know that it exists. But the Clozure CL
          application-building tools create a new application by
          copying resources from the Clozure CL application, so that
          your new application has available to it all the built-in
          Clozure CL tools. We ask you to name your nibfile
          "CurrencyConverter.nib" so that it can coexist with the
          Clozure CL main nibfile without causing any problems.</p>

        <p>This difference between a Lisp project and an Objective-C
        project might be a little confusing at first. Just try to keep
        in mind that whenever Apple's tutorial refers to the
        "MainMenu.nib" file, it means the file we have just created
        and named "CurrencyConverter.nib". In a Clozure CL project,
        "MainMenu.nib" is the name of the main Lisp nibfile, not your
        application's main nibfile.</p>
      </div>

      <div class="section-head">
        <h2>Resize the Window</h2>
      </div>
      
      <p>Make the window smaller by dragging the bottom-right corner
      of the window inward.</p>

      <div class="inline-image">
        <img src="../images/ibwin-tiger3.jpg"alt="" 
             border='0'/>
      </div>
      
      <div class="section-head">
        <h2>Change the Title of the Window</h2>
      </div>
      
      <p>InterfaceBuilder creates the initial window with the title
      "Window". Change the title to the more appropriate "Currency
      Converter":</p>

      <ol>
        <li><p>Click the Window object in the "Currency Converter"
        window.</p>
          <p><div class="inline-image">
              <img src="../images/ibwin-tiger4.jpg"alt="" 
                   border='0'/>
            </div>
        </p></li>
        <li><p>Choose "Attributes" from the drop-down menu in the
        Inspector window:</p>
          <p><div class="inline-image">
              <img src="../images/ibwin-tiger5.jpg"alt="" 
                   border='0'/>
            </div>
        </p></li>
        <li><p>Change the "Window Title" field to read "Currency Converter":</p>
          <p><div class="inline-image">
              <img src="../images/ibwin-tiger6.jpg"alt="" 
                   border='0'/>
            </div>
        </p></li>
      </ol>

      <div class="section-head">
        <h2>Add Text Fields</h2>
      </div>

      <p>In InterfaceBuilder's Palettes window, select the "Cocoa
      Text" view, and find the NSTextView object:</p>

      <div class="inline-image">
        <img src="../images/ibwin-tiger7.jpg"alt="" 
             border='0'/>
      </div>

      <p>Drag an NSTextView object and drop it into the "Currency
      Converter" window:</p>

      <div class="inline-image">
        <img src="../images/ibwin-tiger8.jpg"alt="" 
             border='0'/>
      </div>

      <p>If you drag a view near the edges of a window,
      InterfaceBuilder displays blue guide lines that show the
      standard placement of a view near the edge of the window. Drag
      the text view to the right and upward until the guide lines
      appear, and then let go. The text view is then positioned in
      the standard way.</p>

      <p>Now add two more text fields. You can drag them from the
      palette as you did the first one, or you can duplicate the
      first one. To duplicate, select the first text view and then
      choose "Duplicate" from the "Edit" menu. Alternatively, you can
      option-drag the text field to duplicate it.</p>

      <div class="inline-image">
        <img src="../images/ibwin-tiger9.jpg"alt="" 
             border='0'/>
      </div>

      <div class="section-head">
        <h2>Label the Text Fields</h2>
      </div>

      <p>Now add labels to the text fields, to identify their
      purposes for the user. For each text field, drag a Label object
      from the palette and drop it next to the field. (Alternatively,
      you can drop one Label and then duplicate it, just as you can
      duplicate the text fields.)</p>

      <div class="inline-image">
        <img src="../images/ibwin-tiger10.jpg"alt="" 
             border='0'/>
      </div>

      <p>Just as InterfaceBuilder displayed guidelines to help you
      position the text field near the edge of the window, it also
      displays guide lines to help you position the labels near the
      text fields. Just drag each label until the blue guide lines
      appear, then release the label.</p>

      <p>Now change the text of the labels. Click a label to select
      it. Then show the Inspector by choosing the "Show Inspector"
      item from the "Tools" menu. Select the "Attributes" item from
      the pull-down menu at the top of the Inspector window, and type
      the correct text into the Title field. For example, here is how
      to enter the text for the top label:</p>

      <div class="inline-image">
        <img src="../images/ibwin-tiger11.jpg"alt="" 
             border='0'/>
      </div>

      <p>Here's how the labels should look after you have entered the
      text for all three:</p>

      <div class="inline-image">
        <img src="../images/ibwin-tiger12.jpg"alt="" 
             border='0'/>
      </div>

      <p>When you first enter the text for a label, the label may not
      be wide enough to show it all. In that case, you'll see only
      part of the text in the label. You can resize the label to make
      the full text visible. Click the label to select it. Notice the
      small blue dots that surround it. Grab a dot on the left side
      and drag it to the left to make the label wider, until you can
      see the entire text.</p>

      <div class="section-head">
        <h2>Change Text Field Attributes</h2>
      </div>
      
      <p>The first two text fields accept user input; the last
      displays the result of the conversion. We want the first two
      text fields to be editable, so users can enter the values to use
      in the conversion. We don't want the last field to be editable,
      but we do want users to be able to copy text from it.</p>

      <p>We can control all this behavior using text-field
      attributes, configurable in the Inspector.</p>

      <ol>
        <li><p>Select the first text field</p></li>
        <li><p>Choose "Show Inspector" from the "Tools" menu</p></li>
        <li><p>Make sure "Attributes" is selected in the pull-down
        menu at the top of the Inspector window</p></li>
        <li><p>Ensure that the "Editable" and "Enabled" boxes are
        checked in the "Attributes" display of the Inspector window</p></li>
        <li><p>Repeat this process for the second text field</p></li>
        <li><p>Finally, repeat it again for the last text field, but
        this time make sure the "Editable" box is unchecked</p></li>
      </ol>

      <div class="section-head">
        <h2>Add a Button</h2>
      </div>
      
      <p>Now we add a button that activates the currency conversion.</p>
      
      <ol>
        <li><p>Drag a Button object from the palette and drop it on
            the window</p>
          <p><div class="inline-image">
              <img src="../images/ibwin-tiger13.jpg"alt="" 
                   border='0'/>
            </div>
        </p></li>
        <li><p>Double-click the button and change its title to "Convert"</p>
          <p><div class="inline-image">
              <img src="../images/ibwin-tiger14.jpg"alt="" 
                   border='0'/>
            </div>
        </p></li>
        <li><p>Select the button and then choose "Attributes" from
        the pull-down menu at the top of the Inspector window. Almost
        halfway down the "Attributes" view of the Inspector window,
        find the "Key Equiv" field. Choose "Return" from the pulldown
        menu in that field.</p>
          <p><div class="inline-image">
              <img src="../images/ibwin-tiger15.jpg"alt="" 
                   border='0'/>
            </div>
        </p>
        <p>When you choose "Return", InterfaceBuilder enters "\R" in
        the text field for the Key Equivalent. Now when a user hits
        the "Return" key, your application will behave as if they had
        clicked the "Convert" button.</p></li>
      </ol>

      <div class="section-head">
        <h2>Add a Separator</h2>
      </div>
      
      <p>Now add a separator line to visually group the text fields
      together. Drag a separator line from the palette and drop it
      above the button.</p>
      
      <p><div class="inline-image">
          <img src="../images/ibwin-tiger16.jpg"alt="" 
               border='0'/>
        </div>
      </p>

      <p>Drag the ends of the separator line until it spans a
        visually pleasing width. As always, you can use the blue
        guidelines that InterfaceBuilder displays to adjust the size
        and position of the line and other elements to conform to
        Apple's Human Interface Guidelines.</p>

      <div class="section-head">
        <h2>Set Up the Menus</h2>
      </div>

      <p>InterfaceBuilder creates the standard menus for a new
      application, but it doesn't know the name of the
      application. Consequently, the Application menu and several menu
      items use the name "NewApplication" where they should use the
      name of your application. Change the text of these items so that
      they read "Currency Converter" instead of "NewApplication".</p>

      <ol>
        <li><p>Double-click the text "NewApplication" in the
        application menu of your application's menubar. Change the
        text to "Currency Converter".</p>
          <p><div class="inline-image">
              <img src="../images/ibwin-tiger17.jpg"alt="" 
                   border='0'/>
            </div>
          </p>
        <p><strong>NOTE:</strong> This change isn't really enough to get your
        application to display the right name for the Application menu
        when it's launched; the <a href="build_app.html">section</a>
        on building the application explains how to make sure the
        correct name appears.</p></li>
        <li><p>Repeat this process for each menu item where the name
        "NewApplication" appears. Using the same method you used to
        change the name of the application menu, edit the "About
        NewApplication" item, the "Hide NewApplication" item, and the
        "Quit NewApplication" item in the application menu. Then edit
        the "NewApplication Help" item in the "Help" menu.</p></li>
      </ol>

      <div class="section-head">
        <h2>Tighten Up the Window Layout</h2>
      </div>

      <p>InterfaceBuilder provides layout tools with which you can
      easily clean up the layout of a UI window and ensure it
      conforms to Apple's user interface guidelines.</p>

      <ol>
        <li><p>Select the "Exchange Rate" text label. Then
        Shift-click the other two labels to include them in the
        selection (actually, it doesn't matter which label you select first).</p></li>
        <li><p>Choose "Layout" > "Size to Fit" to shrink the labels
        to the smallest sizes that still show all the text</p></li>
        <li><p>Choose "Layout" > "Alignment" > "Align Right Edges" to
        line up the right sides of the labels</p></li>
        <li><p>With all three labels still selected, drag them up and
        to the left. Release them when the blue guidelines show at
        the top and left side of the window.</p></li>
        <li><p>Now select all three text fields. You can click one of
        them, then Shift-click to add the others to the
        selection. Drag them up and left, toward the labels. Again,
        release them when the blue guide line appears to show you the
        proper distance from the labels. A guide line also appears to
        show you when the fields are vertically aligned with the
        center label.</p></li>
        <li><p>Next, grab the separator line and move it up and to the
        left. Release it when its left edge is aligned with the left
        edge of the bottom label, and its top is the recommended
        distance from the bottom label and its text field. Then drag
        the right end of the separator line to resize it until its
        right edge is aligned with the right edge of the bottom text
        field.  Again, guide lines show when you have found the proper
        distances.</p></li>
        <li><p>Grab the button and move it up and left, again using
        the guide lines to help you find a good position.</p></li>
        <li><p>Finally, resize the window. When the blue guide lines
        appear on the right and bottom of the window, it's the right
        size for its contents.</p></li>
      </ol>

      <p>Now your application window should look something like the
      one in the illustration:</p>

      <p><div class="inline-image">
          <img src="../images/ibwin-tiger18.jpg"alt="" 
               border='0'/>
        </div>
      </p>

      <div class="section-head">
        <h2>Enable Tabbing Between Text Fields</h2>
      </div>

      <p>Users generally expect to be able to use the Tab key to move
      from one text field to the next in a dialog
      box. InterfaceBuilder enables you to specify the tabbing order
      in text fields.</p>

      <ol>
        <li><p>Choose "Layout" > "Keyboard Navigation" > "Show
        Keyboard Check". InterfaceBuilder displays a set of small
        icons that identify UI elements that can respond to key
        events.</p></li>
        <li><p>Select the "Exchange Rate" text field (the field, not
        the label) and then choose "Layout" > "Keyboard Navigation" >
        "Make Initial First Responder". A small "1" icon appears in
        the text field to show that when the application launches,
        that field receives keyboard events.</p></li>
        <li><p>Control-drag from the "Exchange Rate" field to the
        "Dollars" field. InterfaceBuilder shows the "Connections"
        Inspector, and, because Keyboard Check is enabled,
        automatically selects the "nextKeyView" outlet. Click the
        "Connect" button in the Inspector window to confirm.</p></li>
        <li><p>Repeat the previous steps to connect the "Dollars"
        field back to the "Exchange Rate" field. That way, tabbing
        moves the insertion point from the "Exchange Rate" field to
        the "Dollars" field, and then back to the "Exchange Rate"
        field. Control-drag from the "Dollars" field to the "Exchange
        Rate" field, then click "Connect" to confirm.</p></li>
      </ol>

      <p>We don't enable tabbing into the "Amount" field because it's
      not an editable field; it's used only to show the result of a
      conversion.</p>

      <div class="section-head">
        <h2>Set Up the Classes Used In the User Interface</h2>
      </div>

      <p>The visual elements of your application's user interface are
      all ready now. The last thing you must do is create descriptions
      of any custom classes used by the application when users
      interact with the interface.</p>

      <p>When a user clicks the "Convert" button, it should send a
      message to a custom class that causes the conversion to take
      place. In order for the application to connect the user
      interface to classes that perform these actions, you must add
      descriptions of your classes to the nibfile. Fortunately,
      InterfaceBuilder can create class descriptions and save them in
      the nibfile for you.</p>

      <div class="section-head">
        <h3>ConverterController</h3>
      </div>

      <p>ConverterController is the <a href="http://developer.apple.com/documentation/Cocoa/Conceptual/ObjCTutorial/02Essence/chapter_2_section_4.html#//apple_ref/doc/uid/TP40000863-CH3-SW4">controller</a> class that the user
      interface communicates with directly when the "Convert" button
      is pressed. Create a description of the ConverterController
      class, and then create an instance of it.</p>

      <ol>
        <li><p>In InterfaceBuilder's "CurrencyConverter.nib" window,
        click the "Classes" tab. The window shows a browser view of
        all available Objective-C classes:</p>
        <p><div class="inline-image">
          <img src="../images/ibwin-tiger19.jpg"alt="" 
               border='0'/>
        </div></p>
        </li>
        <li><p>Control-click the "NSObject" entry in the browser, and
        choose "Subclass NSObject" from the popup
        menu. InterfaceBuilder creates a new entry initially called
        "MyObject". Change the name from "MyObject" to "ConverterController".</p></li>
        <li><p>Select the "ConverterController" class in the browser,
        then activate the Inspector window and choose "Attributes"
        from the popup menu at the top of the Inspector. At the
        bottom of the "Attributes" view is a list of actions or
        outlets. Select "Outlets", and use the "Add" button to add
        four fields:</p>
        <p><div class="inline-image">
          <img src="../images/ibwin-tiger20.jpg"alt="" 
               border='0'/>
        </div></p>
        <p>Rename these four fields to: "amountField", "dollarField",
        "rateField", and "converter":</p>
        <p><div class="inline-image">
            <img src="../images/ibwin-tiger21.jpg"alt="" 
                 border='0'/>
        </div></p></li>
        <li><p>Now add the action that is triggered when the
        "Convert" button is pressed: switch to the Actions view and
        use the "Add" button to add a new action:</p>
        <p><div class="inline-image">
            <img src="../images/ibwin-tiger22.jpg"alt="" 
                 border='0'/>
        </div></p>
        <p>Change the name of the action from "myAction:" to "convert:"</p></li>
        <li><p>Now create an instance of the ConverterController
        class. In the browser, Right-click the ConverterController
        class and choose "Instantiate ConverterController". The
        browser view automatically switches to the Instances view to
        show you the newly-created instance of ConverterController as
        a blue box icon. There is a small yellow flag next to the
        ConverterController instances to show that it has outlets
        that are not connected to anything. In our final step, we'll
        create the correct connections for the instance's outlets,
        which will enable the application to send messages correctly
        to the objects that implement its behavior.</p></li>
      </ol>

      <div class="section-head">
        <h3>Converter</h3>
      </div>

      <p>Converter is
      the <a href="http://developer.apple.com/documentation/Cocoa/Conceptual/ObjCTutorial/02Essence/chapter_2_section_4.html#//apple_ref/doc/uid/TP40000863-CH3-SW4">model</a>
      class that implements the actual conversion code. Create a
      description of the Converter class, and then create an
      instance of it. Repeat the steps you used to create the
      ConverterController class and instance to create a Converter
      class and instance:</p>

      <ol>
        <li><p>Switch to the browser view in the
        "CurrencyConverter.nib" window.</p></li>
        <li><p>Control-click NSObject and choose "Subclass NSObject"
        from the resulting popup menu.</p></li>
        <li><p>Change the name of the newly-created class from
        "MyObject" to "Converter"</p></li>
        <li><p>Control-click the "Converter" class and choose
        "Instantiate Converter" to create an instance of the
        Converter class.</p></li>
      </ol>

      <p>The model class, "Converter", has no outlets or actions, so
      you don't need to add anything to it before instantiating
      it. Your code will implement a conversion method, but
      InterfaceBuilder doesn't need to know about it; the "convert:"
      method in your code will know everything it needs to about the
      "Converter" class. You just need to create the class
      description and the instance so that your application will
      start up with the correct objects created and connected.</p>

      <div class="section-head">
        <h3>Connecting the Outlets</h3>
      </div>

      <p>The final step in setting up the user interface is
      establishing connections between the outlets and objects in the
      interface, so that messages are sent from the user interface to
      the correct objects.</p>

      <ol>
        <li><p>Connect the "Convert" button to the
        "ConverterController" instance. Control-drag from the
        "Convert" button to the "ConverterController" instance. Make
        sure the "convert:" action is selected in the "Target/Action"
        view of the Inspector window, then click the "connect" button
        to confirm.</p></li>
        <li><p>Connect the "ConverterController" instance to the text
        fields. Control-drag from the "ConverterController" instance
        to the "Exchange Rate" field. Select "rateField" in the
        "Outlets" view of the Inspector window and click "connect" to
        confirm. Then repeat this process, connecting "dollarField" to
        the "Dollars" text field, and "amountField" to the "Amount"
        field.</p></li>
        <li><p>Finally, connect the "ConverterController" to the
        "Converter" instance. Control-drag from the
        "ConverterController" instance to the "Converter"
        instance. Select the "converter" outlet in the Inspector
        window and click "connect" to confirm.</p></li>
      </ol>

      <p>The nibfile now contains descriptions of the custom classes
      that your code will implement, including connections between
      their outlets and the objects with which they must
      communicate. You can save the nibfile and proceed to write the
      code that implements their behavior.</p>

      <p>You can continue now with the section on <a href="create_lisp.html">"Creating a Lisp File"</a>.</p>



    </div>

    <div class="nav">
      <p><a href="../../HOWTO.html">start</a>|<a href="making_project.html">previous</a>|<a href="create_lisp.html">next</a></p>
    </div>
  </body>
</html>

